SherbyNet - /page/wikibook/entry.mu

Micron Document

<!DOCTYPE html>

</head>

JSON-RPC

</h1>

</header>

JSON-RPC (JavaScript Object Notation-Remote Procedure Call) is a <a href="JSON" title="JSON">JSON</a>-based <a href="Wire_protocol" title="Wire protocol">wire protocol</a> for <a href="Remote_procedure_call" title="Remote procedure call">remote procedure calls</a> (RPC). It is similar to the <a href="XML-RPC" title="XML-RPC">XML-RPC</a> protocol, defining only a few data types and commands. JSON-RPC allows for notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server which may be answered asynchronously.

The JSON-RPC protocol is transport-independent and can be carried over many different data transport protocols, including <a href="File_descriptor" title="File descriptor">file descriptor</a> I/O, <a href="HTTP" title="HTTP">HTTP</a> and <a href="TCP" class="mw-disambig" title="TCP">TCP</a>. It does not directly provide any support for authentication or authorization.

<div class="mw-heading mw-heading2"><h2 id="History">History</h2></div>

<th>Version

</th>

<th>Description

</th>

<th>Dated

</th></tr>

<tr>

<td>1.0

</td>

<td><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/specification_v1">Original version</a>

</td>

<td>2005

</td></tr>

<tr>

<td>1.1 WD

</td>

<td><a rel="nofollow" class="external text" href="https://jsonrpc.org/historical/json-rpc-1-1-wd.html">Working draft</a>. Adds named parameters, adds specific error codes, and adds introspection functions.

</td>

<td>2006-08-07

</td></tr>

<tr>

<td>1.1 Alt

</td>

<td><a rel="nofollow" class="external text" href="http://jsonrpc.org/historical/json-rpc-1-1-alt.txt">Suggestion for a simple JSON-RPC 1.1</a>. Alternative proposal to 1.1 WD.

</td>

<td>2007-05-06

</td></tr>

<tr>

<td>1.1 Object Specification

</td>

<td><a rel="nofollow" class="external text" href="http://jsonrpc.org/historical/json-rpc-object-specification.html">Object Specification</a>. Alternative proposal to 1.1 WD/1.1ALT.

</td>

<td>2007-07-30

</td></tr>

<tr>

<td>1.2

</td>

<td><a rel="nofollow" class="external text" href="http://jsonrpc.org/historical/jsonrpc12_proposal.html">Proposal</a>. A later revision of this document was renamed to 2.0.

</td>

<td>2007-12-27

</td></tr>

<tr>

<td>2.0

</td>

<td><a rel="nofollow" class="external text" href="http://jsonrpc.org/historical/json-rpc-1-2-proposal.txt">Specification proposal</a>

</td>

<td>2009-05-24

</td></tr>

<tr>

<td>2.0 (Revised-)

</td>

<td><a rel="nofollow" class="external text" href="http://jsonrpc.org/spec">Specification</a>

</td>

<td>2010-03-26

</td></tr></tbody></table>

<div class="mw-heading mw-heading2"><h2 id="Usage">Usage</h2></div>

JSON-RPC works by sending a request to a server implementing this protocol. The client in that case is typically software intending to call a single method of a remote system. Multiple input parameters can be passed to the remote method as an array or object, whereas the method itself can return multiple output data as well. (This depends on the implemented version.)

All transfer types are single objects, serialized using JSON.<a href="#cite_note-json-rpc1-1">[1]</a> A request is a call to a specific method provided by a remote system. It can contain three members:

<ul><li><code>method</code> - A string with the name of the method to be invoked. Method names that begin with "rpc." are reserved for rpc-internal methods.</li>

<li><code>params</code> - An object or array of values to be passed as parameters to the defined method. This member may be omitted.</li>

<li><code>id</code> - A string or non-fractional number used to match the response with the request that it is replying to.<a href="#cite_note-2">[2]</a> This member may be omitted if no response should be returned.<a href="#cite_note-3">[3]</a></li></ul>

The receiver of the request must reply with a valid response to all received requests. A response can contain the members mentioned below.

<ul><li><code>result</code> - The data returned by the invoked method. If an error occurred while invoking the method, this member must not exist.<a href="#cite_note-4">[4]</a></li>

<li><code>error</code> - An error object if there was an error invoking the method, otherwise this member must not exist.<a href="#cite_note-5">[5]</a> The object must contain members code (integer) and message (string).<a href="#cite_note-6">[6]</a> An optional data member can contain further server-specific data. There are pre-defined error codes which follow those defined for XML-RPC.</li></ul>

<ul><li><code>id</code> - The id of the request it is responding to.</li></ul>

Since there are situations where no response is needed or even desired, notifications were introduced. A notification is similar to a request except for the id, which is not needed because no response will be returned. In this case the <code>id</code> property should be omitted (Version 2.0) or be <code>null</code> (Version 1.0).

<div class="mw-heading mw-heading2"><h2 id="Examples">Examples</h2></div>

In these examples, <code>--></code> denotes data sent to a service (request), while <code><--</code> denotes data coming from a service. Although <code><--</code> is often called a response in client–server computing, depending on the JSON-RPC version it does not necessarily imply an answer to a request.

<div class="mw-heading mw-heading3"><h3 id="Version_2.0">Version 2.0</h3></div>

Request and response:

<div class="mw-highlight mw-highlight-lang-json mw-content-ltr" dir="ltr"><pre>--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}

<-- {"jsonrpc": "2.0", "result": 19, "id": 3}

</pre></div>

Notification (no response):

<div class="mw-highlight mw-highlight-lang-json mw-content-ltr" dir="ltr"><pre>--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Version_1.1_(Working_Draft)">Version 1.1 (Working Draft)</h3></div>

Request and response:

<div class="mw-highlight mw-highlight-lang-json mw-content-ltr" dir="ltr"><pre>--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}

<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Version_1.0">Version 1.0</h3></div>

Request and response:

<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

</pre></div>

<ul><li><a href="GRPC" title="GRPC">gRPC</a> - cross-platform binary RPC protocol</li>

<li><a href="SOAP" title="SOAP">SOAP</a> - a messaging protocol</li>

<li><a href="JSON-WSP" title="JSON-WSP">JSON-WSP</a> - a JSON-RPC inspired protocol with a service description specification</li></ul>

<div class="mw-heading mw-heading2"><h2 id="References">References</h2></div>

/* start https://en.wikipedia.org/ */

.mw-parser-output cite.citation{font-style:inherit;word-wrap:break-word}.mw-parser-output .citation q{quotes:"\"""\"""'""'"}.mw-parser-output .citation:target{background-color:rgba(0,127,255,0.133)}.mw-parser-output .id-lock-free.id-lock-free a{background:url("./mw/Lock-green.svg")right 0.1em center/9px no-repeat}.mw-parser-output .id-lock-limited.id-lock-limited a,.mw-parser-output .id-lock-registration.id-lock-registration a{background:url("./mw/Lock-gray-alt-2.svg")right 0.1em center/9px no-repeat}.mw-parser-output .id-lock-subscription.id-lock-subscription a{background:url("./mw/Lock-red-alt-2.svg")right 0.1em center/9px no-repeat}.mw-parser-output .cs1-ws-icon a{background:url("./mw/Wikisource-logo.svg")right 0.1em center/12px no-repeat}body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-free a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-limited a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-registration a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-subscription a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .cs1-ws-icon a{background-size:contain;padding:0 1em 0 0}.mw-parser-output .cs1-code{color:inherit;background:inherit;border:none;padding:inherit}.mw-parser-output .cs1-hidden-error{display:none;color:var(--color-error,#d33)}.mw-parser-output .cs1-visible-error{color:var(--color-error,#d33)}.mw-parser-output .cs1-maint{display:none;color:#085;margin-left:0.3em}.mw-parser-output .cs1-kern-left{padding-left:0.2em}.mw-parser-output .cs1-kern-right{padding-right:0.2em}.mw-parser-output .citation .mw-selflink{font-weight:inherit}@media screen{.mw-parser-output .cs1-format{font-size:95%}html.skin-theme-clientpref-night .mw-parser-output .cs1-maint{color:#18911f}}@media screen and (prefers-color-scheme:dark){html.skin-theme-clientpref-os .mw-parser-output .cs1-maint{color:#18911f}}

/* end https://en.wikipedia.org/ */

</style><cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://web.archive.org/web/20080517011921/http://json-rpc.org/wiki/specification">"specification - JSON-RPC - Trac"</a>. Archived from <a rel="nofollow" class="external text" href="http://json-rpc.org/wiki/specification">the original</a> on 2008-05-17. Retrieved 2008-05-14.</cite>

</li>

<li id="cite_note-2"><a href="#cite_ref-2">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/specification">"JSON-RPC 2.0 Specification"</a>. <q>id: An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts</q></cite>

</li>

<li id="cite_note-3"><a href="#cite_ref-3">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/specification">"JSON-RPC 2.0 Specification"</a>. <q>A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request. Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params", "Internal error").</q></cite>

</li>

<li id="cite_note-4"><a href="#cite_ref-4">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/specification">"JSON-RPC 2.0 Specification"</a>. <q>result: This member is REQUIRED on success. This member MUST NOT exist if there was an error invoking the method. The value of this member is determined by the method invoked on the Server.</q></cite>

</li>

<li id="cite_note-5"><a href="#cite_ref-5">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/specification">"JSON-RPC 2.0 Specification"</a>. <q>error: This member is REQUIRED on error. This member MUST NOT exist if there was no error triggered during invocation. The value for this member MUST be an Object as defined in section 5.1.</q></cite>

</li>

<li id="cite_note-6"><a href="#cite_ref-6">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/specification">"JSON-RPC 2.0 Specification"</a>. <q>Error object: When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members: (code) - A Number that indicates the error type that occurred. This MUST be an integer. (message) - A String providing a short description of the error. The message SHOULD be limited to a concise single sentence. (data) - A Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).</q></cite>

</li>

</ol>

<div class="mw-heading mw-heading2"><h2 id="External_links">External links</h2></div>

<ul><li><a rel="nofollow" class="external text" href="https://www.jsonrpc.org/">Official website</a> </li>

<li><a rel="nofollow" class="external text" href="https://groups.google.com/group/json-rpc">JSON-RPC Google Group</a> discussing topics of and around the protocol</li>

<li><a rel="nofollow" class="external text" href="http://www.simple-is-better.org/json-rpc/">JSON-RPC specifications, MNlinks etc.</a></li>

<li><a rel="nofollow" class="external text" href="http://www.simple-is-better.org/json-rpc/transport_http.html">HTTP transport</a> description for JSON-RPC-2</li>

<li><a rel="nofollow" class="external text" href="https://open-rpc.org">OpenRPC Specification</a> Service description format for JSON-RPC. (open-api, but for json rpc)</li>

<li><a rel="nofollow" class="external text" href="https://github.com/omniti-labs/jsend">JSend</a> - a similar specification which defines only format of response</li></ul></div><div><div class="zim-footer">

This article is issued from <a class="external text" title="Last edited on 2025-06-05" href="https://en.wikipedia.org/wiki/?title=JSON-RPC&oldid=1294068170">Wikipedia</a>. The text is available under <a class="external text" href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">Creative Commons Attribution-Share Alike 4.0</a> unless otherwise noted. Additional terms may apply for the media files.

</div>

</div></div>

</div>

</main>

</div>

</body></html>